Selects and optionally retrieves a specific high-level event from your application’s high-level event queue.

Boolean GetSpecificHighLevelEvent (
    GetSpecificFilterUPP aFilter, 
    void *contextPtr, 
    OSErr *err
);

aFilter

A universal function pointer to the application-defined filter function that GetSpecificHighLevelEvent should use to search for a specific event; see GetSpecificFilterProcPtr for details. GetSpecificHighLevelEvent calls your filter function once for each event in your application’s high-level event queue until the function returns true or the end of the queue is reached.

contextPtr

A pointer to a value that specifies the criteria your filter function should use to select a specific event. For example, you can specify the address of a reference constant to search for a particular event, the address of a target ID structure to search for a specific sender of an event, or the address of an event class to search for a specific class of event.

err

GetSpecificHighLevelEvent returns, through this parameter, a value that indicates whether any errors occurred. The err parameter specifies the noErr constant if no errors occurred or noOutstandingHLE if no high-level events are pending in your application’s high-level event queue.

DISCUSSION

You can use the GetSpecificHighLevelEvent function to search for a specific high-level event in your application’s high-level event queue. You specify a filter function as one of the parameters to GetSpecificHighLevelEvent. The GetSpecificHighLevelEvent function calls your filter function once for every event in your application’s high-level event queue, until your filter function returns true or the end of the queue is reached.

The GetSpecificHighLevelEvent function passes the value referenced by the contextPtr parameter to your filter function. Your filter function also receives as parameters the event structure associated with the high-level event and the target ID structure that identifies the sender of the event. Your filter function can compare the value referenced by the contextPtr parameter with any of the other information it receives.

If your filter function finds a match, it can call AcceptHighLevelEvent if necessary, and then return true. If your filter function does not find a match, then it should return false.

If your filter function returns true, the GetSpecificHighLevelEvent function returns true. If your filter function returns false for all high-level events in your application’s event queue, or if there are no high-level events in the queue, GetSpecificHighLevelEvent returns false.

See GetSpecificFilterProcPtr for more information about how to define a filter function and the parameters that GetSpecificHighLevelEvent passes to your filter function.

SPECIAL CONSIDERATIONS

The GetSpecificHighLevelEvent function may move or purge memory. You should not call this function from within an interrupt, such as in a completion function or VBL task.

AVAILABILITY

Not supported in Carbon. Not available in Carbon.

CARBON NOTES

The High Level Event APIs (EPPC.h) are not supported in Carbon. Instead, use Apple events.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)